录音（电平测量）

AudioRecorder 类允许您将音频数据录制到文件。它提供了开始、停止、暂停和管理音频录制的功能，并可配置音频质量、采样率、格式等。

功能

从系统的活跃输入设备录制音频。
可以录制指定时长，或在手动停止前一直录制。
暂停并恢复录制。
删除已录制的音频文件。

用法

设置 SharedAudioSession

在创建 AudioRecorder 实例之前，需要先设置 SharedAudioSession。因为音频会话与硬件相关，因此需要确保正确激活会话。

await SharedAudioSession.setActive(true)
await SharedAudioSession.setCategory(
  "playAndRecord",
  ["defaultToSpeaker"]
)

创建 AudioRecorder 实例

使用 create 方法来创建一个音频录制器实例：

async function createRecorder() {
  try {
    const filePath = Path.join(
      FileManager.documentsDirectory,
      "recording.m4a"
    )
    const recorder = await AudioRecorder.create(filePath, {
      format: "MPEG4AAC",
      sampleRate: 44100,
      numberOfChannels: 2,
      encoderAudioQuality: AVAudioQuality.high
    })
    return recorder
  } catch (error) {
    console.error("Failed to create recorder: ", error)
  }
}

录制音频

您可以使用 record() 方法开始录制：

async function startRecording() {
  const recorder = await createRecorder()
  if (recorder) {
    const success = recorder.record()
    console.log("Recording started: ", success)
  }
}

也可以提供额外的选项来控制录制开始的时间及录制时长：

function startSynchronizedRecording(recorderOne, recorderTwo) {
  let timeOffset = recorderOne.deviceCurrentTime + 0.01
  
  // 使两个 recorder 的录制时间同步
  recorderOne.record({ atTime: timeOffset })
  recorderTwo.record({ atTime: timeOffset })
}

暂停和停止录制

暂停录制：

function pauseRecording(recorder) {
  recorder.pause()
  console.log("Recording paused.")
}

停止录制：

function stopRecording(recorder) {
  recorder.stop()
  console.log("Recording stopped.")
}

删除录音文件

要删除已经录制好的文件：

function deleteRecording(recorder) {
  const success = recorder.deleteRecording()
  console.log("Recording deleted: ", success)
}

释放 Recorder

当不再需要使用录制器时，应调用 dispose() 来释放资源：

function disposeRecorder(recorder) {
  recorder.dispose()
  console.log("Recorder disposed.")
}

事件处理

可以使用 onFinish 和 onError 回调来处理录制完成和错误情况：

async function setupRecorder() {
  const recorder = await createRecorder()
  if (recorder) {
    recorder.onFinish = (success) => {
      console.log("Recording finished successfully: ", success)
    }

    recorder.onError = (message) => {
      console.error("Recording error: ", message)
    }
  }
}

电平表（VU meter / 音量条）

AudioRecorder 在录制过程中可以输出输入信号的平均功率与峰值功率（dBFS），用于绘制 VU 表或基于响度做触发逻辑，但不会暴露原始 PCM 数据。

可以在创建时打开 meteringEnabled，也可以在调用 record() 之前设置该属性：

const recorder = await AudioRecorder.create(filePath, {
  format: "MPEG4AAC",
  sampleRate: 44100,
  numberOfChannels: 1,
  meteringEnabled: true,
  // 可选：onLevelUpdate 触发的间隔，单位毫秒，clamp 到 [16, 1000]，默认 50。
  levelUpdateInterval: 50,
})

recorder.onLevelUpdate = (level) => {
  // averagePower / peakPower 单位是 dBFS，大致范围 [-160, 0]
  // 映射到 0..1 的进度条可以参考：
  const norm = Math.max(0, (level.averagePower + 60) / 60)
  console.log(`avg=${level.averagePower.toFixed(1)} dB peak=${level.peakPower.toFixed(1)} dB`)
}

recorder.record()

也可以不使用回调，自己手动轮询：

recorder.meteringEnabled = true
recorder.record()

setInterval(() => {
  recorder.updateMeters()
  const avg = recorder.averagePower(0)
  const peak = recorder.peakPower(0)
  console.log(`channel 0 → avg=${avg} peak=${peak}`)
}, 100)

电平定时器在 pause() / stop() / dispose() 时自动停止，下一次 record() 时若 onLevelUpdate 仍然存在则会自动恢复。

如果需要原始 PCM 采样、实时波形数据或音高检测，请改用 AudioCapture 。 AudioRecorder 主要用于把编码后的音频写入文件（m4a / aac / flac / opus / mp3 / wav）。

API 参考

`AudioRecorder.create(filePath, settings?)`

使用指定的设置创建一个 AudioRecorder 实例。

filePath (string): 要录制到的文件系统路径。
settings (可选对象): 录音的音频设置：
- format (AudioFormat): 音频数据的格式，可选值包括 "LinearPCM", "MPEG4AAC", "AppleLossless", "AppleIMA4", "iLBC", "ULaw"。
- sampleRate (number): 采样率，单位为赫兹 (范围 8000 到 192000)。
- numberOfChannels (number): 声道数量 (1 到 64)。
- encoderAudioQuality (AVAudioQuality): 音频编码质量 (从 AVAudioQuality.min 到 AVAudioQuality.max)。

返回值: 一个 Promise，解析后返回 AudioRecorder 实例。

`AudioRecorder.isRecording`

一个布尔值，用于指示录制器当前是否正在录音。

`AudioRecorder.currentTime`

从录音开始到当前的时间（单位为秒）。

`AudioRecorder.deviceCurrentTime`

主机音频设备的当前时间（单位为秒）。

`AudioRecorder.record(options?)`

开始录制音频。

options (可选对象):
- atTime (number): 相对于 deviceCurrentTime，指定开始录制的时间。
- duration (number): 录音时长（单位为秒）。

返回值: 一个布尔值，表示录制是否成功开始。

`AudioRecorder.pause()`

暂停当前录制。

`AudioRecorder.stop()`

停止录制并关闭音频文件。

`AudioRecorder.deleteRecording()`

删除已经录制的音频文件。

返回值: 一个布尔值，表示删除操作是否成功。

`AudioRecorder.dispose()`

释放录制器所使用的资源。

`AudioRecorder.onFinish`

录音完成后调用的回调函数。

success (boolean): 表示录制是否成功完成。

`AudioRecorder.onError`

在录制或编码出现错误时调用的回调函数。

message (string): 描述错误的字符串。

`AudioRecorder.meteringEnabled`

是否启用电平测量。在 record() 之前打开（或在 create 时传 meteringEnabled: true）， averagePower、peakPower 与 onLevelUpdate 才会有数据。

`AudioRecorder.levelUpdateInterval`

onLevelUpdate 的触发间隔，单位毫秒。Clamp 到 [16, 1000]，默认 50。

`AudioRecorder.updateMeters()`

刷新电平值。如果不使用 onLevelUpdate，需要在读取 averagePower / peakPower 前调用。

`AudioRecorder.averagePower(channel?)`

返回指定声道的平均功率（dBFS），大致范围 [-160, 0]。未启用电平测量或未在录音时返回 0。

channel (number, 可选): 声道索引，默认 0。

`AudioRecorder.peakPower(channel?)`

返回指定声道的峰值保持功率（dBFS）。

`AudioRecorder.onLevelUpdate`

录音过程中按 levelUpdateInterval 频率触发的回调（仅在 meteringEnabled === true 时）。

level.averagePower (number): 各声道平均功率的均值（dBFS）。
level.peakPower (number): 各声道峰值功率的均值（dBFS）。
level.channels ({ average; peak }[]): 每个声道的具体值。
level.timestamp (number): 采样时刻的 deviceCurrentTime（秒）。

使用示例

import { Path } from 'scripting'

async function run() {

  await SharedAudioSession.setActive(true)
  await SharedAudioSession.setCategory(
    "playAndRecord",
    ["defaultToSpeaker"]
  )

  try {
    const filePath = Path.join(
      FileManager.documentsDirectory,
      "recording.m4a"
    )
    const recorder = await AudioRecorder.create(filePath, {
      format: "MPEG4AAC",
      sampleRate: 48000,
      numberOfChannels: 2,
      encoderAudioQuality: AVAudioQuality.high
    })

    recorder.onFinish = (success) => console.log("Recording finished successfully: ", success)
    recorder.onError = (message) => console.error("Recording error: ", message)

    recorder.record()
    setTimeout(() => {
      recorder.stop()
    }, 5000) // 5秒后停止录制
  } catch (error) {
    console.error("Error: ", String(error))
  }
}

run()

使用 AudioRecorder 类，您可以在脚本中轻松管理音频录制操作，并灵活控制音频录制流程。

录音（电平测量）#

#功能

#用法

#设置 SharedAudioSession

#创建 AudioRecorder 实例

#录制音频

#暂停和停止录制

#删除录音文件

#释放 Recorder

#事件处理

#电平表（VU meter / 音量条）

#API 参考

#AudioRecorder.create(filePath, settings?)

#AudioRecorder.isRecording

#AudioRecorder.currentTime

#AudioRecorder.deviceCurrentTime

#AudioRecorder.record(options?)

#AudioRecorder.pause()

#AudioRecorder.stop()

#AudioRecorder.deleteRecording()

#AudioRecorder.dispose()

#AudioRecorder.onFinish

#AudioRecorder.onError

#AudioRecorder.meteringEnabled

#AudioRecorder.levelUpdateInterval

#AudioRecorder.updateMeters()

#AudioRecorder.averagePower(channel?)

#AudioRecorder.peakPower(channel?)

#AudioRecorder.onLevelUpdate

#使用示例